[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
V_STUFF()
Delete and insert new data into an existing VLF
-------------------------------------------------------------------------------
Syntax
V_STUFF( <cOldPointer>,
<nStart>,
<nDelete>,
<cNewString> ) -> cNewPointer
Arguments
<cOldPointer> Is the pointer (usually stored in a DBF field),
which points to the source string into which <cNewString> will be
V_STUFF()ed.
<nStart> is the starting position in the VLF where <cNewString>
will be inserted.
<nDelete> is the number of characters to delete from <cNewString>
starting at <nStart>. Deletions are performed before insertions.
<cNewString> is a string which will be inserted at the <nStart>
position after the deletion of <nDelete> characters.
Returns
V_STUFF() returns a pointer which should be stored in the field
with which the modified variable length data is to be associated.
V_STUFF() returns (.F.) on error. This causes the error system to
be invoked with a "Data Type Mismatch". Use V_ERROR() to fetch
the specific error value (see Appendix B for a table of error
descriptions).
Description
The V_STUFF() function works on VLFs much as Clipper's STUFF()
works on strings. Working on VLFs, V_STUFF() will delete <nDelete>
characters from the string pointed to by <cOldPointer> and then
insert <cNewString> at the <nStart> position. V_STUFF() can,
therefore, perform the following seven functions:
. Insert: If <nDelete> is zero, V_STUFF() will not delete any
characters before inserting <cNewString> at the <nStart> position.
This effectively makes V_STUFF() an insert function.
. Replace: If <nDelete> equals LEN( <cNewString> ), then
V_STUFF() will effectively replace the data beginning at the
<nStart> position. If the <cNewString> is always the same length
as <nDelete> or if the comparison for equivalent length is easily
tested, it is faster (less disk I/O) to use V_POKE().
. Delete: If LEN( <cNewString> ) == 0 or <cNewString> is not
passed, V_STUFF() will effectively delete <nDelete> characters
beginning at the <nStart> position.
. Replace and Insert: If <cNewString> is longer than <nDelete>,
V_STUFF() will replace <nDelete> characters of the data pointed to
by <cOldPointer> and insert the remaining length of <cNewString>.
. Replace and Delete: If <cNewString> is shorter than <nDelete>,
V_STUFF() will replace <nDelete> characters of the data pointed to
by <cOldPointer> and then delete the remaining <nDelete>
characters making the data shorter.
. Replace and Delete rest: If <nDelete> is greater than or equal
to the number of characters remaining after the <nStart> position
of the data pointed to by <cOldPointer>, the old data is
effectively trimmed at the <nStart> position before the
<cNewString> is inserted.
. Append: If <nStart> is equal to or greater than the length of
the data pointed to by <cOldPointer>, the <nDelete> parameter is
ignored and the <cNewString> data is appended to the end.
+-------------------------- WARNING --------------------------+
| V_STUFF() deletes the data associated with <cOldPointer> |
| before returning <cNewPointer>. Attempting to use |
| <cOldPointer> after this function deletes the data that it |
| points to can corrupt the DBV file. |
+-------------------------------------------------------------+
Notes
The big advantage to V_STUFF() is that its operation is disk based
rather than memory based. This is, however, a double edged sword.
On the one hand, it offers the ability to create a VLF that is
larger than 65K (Clipper's largest character string size). On the
other hand, if you are not aware that <cNewPointer> points to data
that is larger than 65K, you may be surprised when V_RETRIEVE() or
similar functions trim their return value to 65K. Although
V_RETRIEVE() can only return a maximum length of 65K, it can pick
up any portion of a longer string as long as the portion itself is
no longer than 65K (see V_REPLACE()).
In all cases, V_STUFF() will move the data pointed to by
<cOldPointer> to a new location in the DBV file. It is, therefore,
less disk intensive to use V_POKE() where possible. V_POKE() does
not delete or insert, but simply overwrites data leaving it at the
same disk location within the DBV file.
Examples
// Open a DBF file and its associated DBV file.
USE dbf_file
V_USE( "dbv_file" )
// Put a string away.
cStr = "ABCDEF"
REPLACE vlf WITH V_REPLACE( cStr, vlf )
// Insert.
REPLACE vlf WITH V_STUFF( vlf, 2, 0, 'xyz' )
? V_RETRIEVE( vlf ) // Result: AxyzBCDEF
// Replace.
REPLACE vlf WITH V_STUFF( vlf, 2, 3, 'qrs' )
? V_RETRIEVE( vlf ) // Result: AqrsBCDEF
// Delete.
REPLACE vlf WITH V_STUFF( vlf, 2, 3, '' )
? V_RETRIEVE( vlf ) // Result: ABCDEF
// Replace and Insert.
REPLACE vlf WITH V_STUFF( vlf, 2, 2, 'xyz' )
? V_RETRIEVE( vlf ) // Result: AxyzDEF
// Replace and delete.
REPLACE vlf WITH V_STUFF( vlf, 2, 4, 'qrs' )
? V_RETRIEVE( vlf ) // Result: AqrsEF
// Replace and delete rest.
REPLACE vlf WITH V_STUFF( vlf, 2, 10, 'xyz' )
? V_RETRIEVE( vlf ) // Result: Axyz
// Append.
REPLACE vlf WITH V_STUFF( vlf, 10, 0, 'qrs' )
? V_RETRIEVE( vlf ) // Result: Axyzqrs
See Also:
V_POKE()
V_REPLACE()
V_LEN()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson